feat(spec): every metadata.endpoints.* switch gates exactly the face its name states, and the whole-store operations get their own key maintenance - #16243

Fixes #15542
Closes #15854

Implements the maintainer ruling recorded on #15542 (comment 5557095147, director seat, batch #53): an endpoints.* switch gates exactly the face its name states, reads and writes alike. Both halves land here because they are one re-partition of one surface — #15854 is this card's converse mismatch, one switch over.

#15854 closes with this PR rather than being merely referenced by it, by its own ruling (comment 5557098503, item 1): "both halves are one domain:spec PR, and this card closes when that PR lands." Its pm:retriage is scoped by item 2 to the ROUTING question only — re-route to domain:spec, or close as a duplicate half — and every branch of that question still ends with the card closed on landing. So the body says Closes #15854; it deliberately does not also carry a part-of declaration, which the "Part-of PR must not also close its card" gate forbids pairing with a close.

⛔ Draft on purpose, and it must stay that way. Clause-② is yes; claude-fable-5-1 was exhausted platform-wide when this was dispatched, so construction ran at claude-opus-5 under the quota-exhaustion exemption. Review does not take that exemption. Do not flip ready and do not enqueue until an at-tier needs:contract-review PASS exists.

The defect, in both directions at once

RestServerConfig.metadata.endpoints declared three switches, each describe() naming exactly one route, and each gated a different set:

So an operator who switched off a listing read they considered chatty silently unmounted a migration write door; and an operator who closed the per-item surface left its writes mounted. Neither is a liveness defect — all three keys were genuinely read — which is why no ADR-0049 census could flag either: what drifted was each key's radius against its own documentation, the axis the ledger structurally cannot see.

The code's own routing comment already separated "whole-store operations (/diagnostics, /_drafts, /_migrate-stored)" from "the per-type list (/:type)". The taxonomy was ahead of the switch surface. This makes the switches equal to it.

What lands

• packages/spec/src/api/rest-server.zod.ts — the new key, and all four describe() strings rewritten to enumerate what they gate. The radius is the contract now, not a sample of it.
• packages/rest/src/rest-server.ts — the three whole-store gates read maintenance; the per-item family's later members (PUT, DELETE, history, audit, publish, rollback, diff, published) go through a new local registerPerItemRoute, which carries the same endpoints.item switch.
• packages/rest/src/rest-config-mount-table.pin.test.ts — the [finding] The MOUNT half of every RestServerConfig switch is unpinned — the tests assert what a switch normalizes to, never that the route leaves the table #15544 mount-absent pins re-stated on the new radii, not deleted (ruling item 5). Each key keeps a row asserting the exact set of routes that leaves when it is false, in both directions, each with its presence twin. The §0 exhaustiveness count moves 19 → 20 with the new switch.
• packages/rest/src/rest-meta-auth.test.ts — a new anonymous-deny pin on a helper-routed per-item route (see the repair-round section).
• packages/qa/dogfood/test/authz-probe-blind-spot.census.ts — the authz blind-spot population rule learns the registerPerItemRoute( spelling (see the repair-round section).
• packages/spec/liveness/metadata_endpoints.json — a maintenance row, and radius notes on items / item recording that the move was ruled rather than drifted.
• packages/spec/src/migrations/entries/semantic/18.metadata-endpoints-switch-radius-repartitioned.ts — the ADR-0087 D3 prescription (see below).
• docs/qa/platform-checklist/ — see below; the acceptance clause is kept and re-pointed, never retired.

Why registerPerItemRoute is a call and not one more if block

Two reasons, neither cosmetic. (1) No single brace pair contains exactly the right set: the later members of the per-item face are spread over ~1200 lines with GET /meta/object/:name/state/:field — deliberately not part of that face — sitting among them. (2) A gate that travels with its registration cannot be inherited or shed by moving a route past a brace, which is precisely how this switch came to gate four reads and none of its own writes. It reads this.routeManager at call time, deliberately: registerMetadataEndpoints swaps in the anonymous-deny wrapping registrar for the duration of the method, so a captured reference would register past that gate.

A secondary benefit is diff hygiene on a busy cross-lane file: wrapping those eight registrations in if blocks would have re-indented ~1200 lines of rest-server.ts for no behavioural gain.

One route deliberately left alone

GET /meta/object/:name/state/:field — the object FSM read, addressed by object name rather than by :type/:name — is in no per-family switch and still answers to api.enableMetadata alone. The ruling's enumeration does not name it, so moving it under a switch would be a fresh decision, not a tidy-up. It is called out in the registrar docblock and in the pin table so the next reader does not read its absence as an oversight.

BREAKING — priced and accepted (ruling item 6)

For a programmatic embedder that authors RestServerConfig.metadata.endpoints, the mounted table moves for two keys, in opposite directions:

• items: false removes one route instead of four. An embedder relying on it to close the whole-store family regains all three routes, the write door among them, unless it also sets maintenance: false. One line restores the old table: endpoints: { items: false, maintenance: false }.
• item: false removes twelve instead of four. An embedder relying on it to close only the per-item reads loses PUT, DELETE and the history family too. No key restores them — the per-item face is one face by this ruling.
• The exported type MetadataEndpointsConfigParsed narrows: endpoints gains a REQUIRED member maintenance: boolean. maintenance is z.boolean().default(true) — optional on the way in, always present on the way out — and MetadataEndpointsConfigParsed is z.infer of the schema, the OUTPUT side. Code that hand-builds one of these objects (a fixture, a helper returning the parsed shape, a satisfies literal) stops compiling with TS2741: Property 'maintenance' is missing. This one is compiler-carried, the ADR-0087 D8 class, and that is the good case: loud, at build time, no changelog reading required. In-repo consumers of the type: none — measured against a probe compiled from the rebuilt declaration, not assumed.

Measured blast radius today is zero: RestServerConfig is reachable from no shipped boot path (#15543 — os serve pins the config and the dev plugin passes none), so the affected population is programmatic embedders only. That is exactly why it lands now rather than after a boot path starts authoring it.

ADR-0087 disposition: a D3 semantic migration is REGISTERED; no D2 conversion. The changeset carries adr-0087: registered metadata-endpoints-switch-radius-repartitioned and check-adr-0087-registration accepts it as new in this diff. There is nothing for the conversion layer to convert — no key is renamed, removed or retyped, and a RestServerConfig is plugin TS configuration, never a stack collection member and never a sys_metadata row (the RestServerConfig.openApi31 precedent, #4579), so no rehydration seam sees it. But an embedder is owed a prescription, because the channel that would otherwise reach them is blind for the RADIUS change: every authored key is an optional boolean, so { items: false } still compiles and still parses and simply mounts a different table. (The parsed-type narrowing above is compiler-carried, but it catches only code that hand-builds the OUTPUT type — it cannot reach the embedder who authored { items: false } and now silently gets three routes back.) A D2 conversion could not decide the question either — rewriting { items: false } to { items: false, maintenance: false } preserves the old mounts but presumes an intent the author never expressed, and leaving it alone re-mounts a write door. That judgment is delegated, which is exactly what D3 is for.

The checklist item is kept satisfiable, not made vacuous (ruling item 7)

docs/qa/platform-checklist/areas/api-backend.json → api-backend.rest-metadata-config-contract is at revision 2. Its acceptance clause still requires a run to ENUMERATE each switch's real radius from a route-table diff rather than trust the describe(); what changed is the expected sets, plus a fourth maintenance step and the both-directions rule (a switch that grows a route is as much a FAIL as one that loses one). Left stale it would not have gone vacuous — it would have produced a false FAIL against the new radii, which is worse. FOLLOW-UPS.md §10b E1 records the ruling and points at revision 2; §10b E3's "nineteen gates pinned" is refreshed to twenty.

Declared scope increments (for the PM)

Three paths outside the claim's declared file surface, all named here rather than folded in silently:

1. docs/qa/platform-checklist/** — required by ruling item 7, as above. Not optional: the alternative is a checklist item that fails against the tree it is meant to measure.
2. packages/spec/liveness/metadata_endpoints.json — a new declared key needs its ADR-0049 ledger row, and items / item carry radius notes that were measured statements about the old gates.
3. packages/spec/src/migrations/entries/semantic/ + the generated registry.ts — check-adr-0087-registration refuses a **BREAKING** changeset with no disposition marker, and not-required (no-migration-prescription) is unavailable to a body that (correctly) prescribes one. Registering was the honest answer, not a wider scope.

Plus content/docs/permissions/system-context.mdx, which is line-anchored into rest-server.ts and was re-anchored mechanically by check-system-context-census --fix (10 anchors, no prose change).

One bounded in-place fix in the same docblock this card rewrites: MetadataEndpointsConfigSchema's @example advertised endpoints: { types, objects, fields } — two keys the schema has never declared. It is the same declared-versus-real class the card is about, sitting three lines above the block being changed, and it now shows the four real keys.

Repair round at 57b8e451ac — the authz blind-spot census

Dogfood Regression Gate (3/3) was red on the previous head 484601894 (run 34019739422, job 101450083462, failed 07:50:38Z), and it was caused by this diff.

authz-probe-blind-spot.census.ts records rest-server.ts at population 80 / reachable 19 / blind spot 61, under the rule "this.routeManager.register( call sites; reachable = those inside registerMetadataEndpoints". registerPerItemRoute moved 8 sites off that spelling and added 1 back inside the helper, so the old rule read 73 / 12.

⛔ 73 / 12 was NOT re-recorded. Those 8 routes are still mounted and still registered where they were; only the spelling of the call changed. Writing the lower number down would have ratified a false population and encoded a 7-route hole in the very census that exists to find routes the probe cannot see — the failure it is named for, committed by its own record.

First: are the 8 helper-routed routes still reachable by the probe? Yes — checked before the count was widened, because if the helper hid them the repair would belong in rest-server.ts instead. registerPerItemRoute reads this.routeManager at call time, and all 8 call sites are lexically inside registerMetadataEndpointsInner, which registerMetadataEndpoints runs with this.routeManager swapped to the anonymous-deny guardedRouteManager and restored in a finally. So a helper-routed registration is wrapped identically to the 11 remaining direct sites, and the umbrella key meta:rest-server.ts:registerMetadataEndpoints covers it unchanged. That is now measured, not argued: a new case in rest-meta-auth.test.ts drives an anonymous GET /meta/:type/:name/history — a helper-routed route — to 401 UNAUTHENTICATED with historyMetaItem never called. Before this PR that whole half of the surface had no test proving it is anonymously denied.

The rule now counts both spellings, excluding the helper's own forwarding call so it is not double-counted. The decomposition: 72 direct + 8 helper-routed = 80; 11 + 8 = 19 reachable. blindSpot stays 61 and both repo-wide totals are unchanged. The control this.routeManager.register( is re-recorded 80 → 73 (it is a control on the file, not the population) and two new exact controls — registerPerItemRoute( = 8 and const registerPerItemRoute = = 1 — guard the new half so neither can go silently to zero.

Ablation — the widened rule still discriminates. A rule that counts everything is as useless as one that counts nothing, so both halves were ablated independently against the real deriveProbeFileCensus(), each proved on disk and restored from HEAD:

LEG B — helper-routed half (a registerPerItemRoute call site removed)
  PRE  on-disk: deleted-text=8  injected=0     PRE  population=80 reachable=19 directCtl=73 helperCtl=8
  POST on-disk: deleted-text=7  injected=1     POST population=79 reachable=18 directCtl=73 helperCtl=7
  MUTATED blob=f4d0422d…  (HEAD was 4d20c874…)
  RESTORE blob=4d20c874…  matches-HEAD=yes  git-diff-HEAD-empty=yes

LEG A — direct half (a this.routeManager.register call site removed)
  PRE  on-disk: deleted-text=72 injected=0     PRE  population=80 reachable=19 directCtl=73 helperCtl=8
  POST on-disk: deleted-text=71 injected=1     POST population=79 reachable=18 directCtl=72 helperCtl=8
  MUTATED blob=0f4b64e3…  (HEAD was 4d20c874…)
  RESTORE blob=4d20c874…  matches-HEAD=yes  git-diff-HEAD-empty=yes

LEG C — fail-loud (helper declaration renamed so the forwarder slice MISSES)
  POST population=81 reachable=20   -- ONE HIGH, i.e. RED. It never silently shrinks.

Leg B is the load-bearing one: it is the new half, and removing one helper-routed registration drops the population by exactly one. Leg A shows the widening did not turn the old half into a count-everything. Leg C shows the forwarder slice fails loud rather than quiet if the helper moves out of shape. No build step is involved and none is owed: deriveProbeFileCensus() reads rest-server.ts as text through readFileSync, imports nothing from @objectstack/rest and resolves through no dist/ — so there is no stale-dist false-green risk here, and the readings above moved with nothing rebuilt.

The changeset's BREAKING paragraph also gained the MetadataEndpointsConfigParsed narrowing (third bullet above), which was implemented but not written down.

Verification

Figures for the contract increment were measured at 484601894; the repair-round figures at 57b8e451ac, the final commit.

Repair round — bash scripts/pm/os-verify-lock.sh -c …, reading each run's own VERDICT line:

authz-probe-blind-spot.test.ts   Test Files 1 passed (1)   Tests 33 passed (33)   VERDICT command-exit 0
rest-meta-auth.test.ts           Test Files 1 passed (1)   Tests  4 passed  (4)   VERDICT command-exit 0
typecheck @objectstack/dogfood + @objectstack/rest        both "Done"            VERDICT command-exit 0

Baseline red reproduced locally before the fix, matching CI byte for byte: expected 73 to be 80 plus control "this.routeManager.register(" moved in packages/rest/src/rest-server.ts, Tests 2 failed | 31 passed (33).

⚠️ One NOT-MEASURED, stated rather than implied. packages/rest's typecheck does not compile its test layer — tsc --noEmit --listFiles names rest-meta-auth.test.ts 0 times (pre-existing: check:test-typecheck reports the rest test layer at 0 files). The new case is therefore executed by vitest (green) but not type-checked. packages/qa/dogfood's tsc does compile the census — --listFiles names it once — so that edit is type-checked.

Contract increment, at 484601894 — pnpm --filter @objectstack/spec --filter @objectstack/rest run test, VERDICT command-exit 0:

packages/spec test:  Test Files  482 passed (482)   Tests  13102 passed (13102)
packages/rest test:  Test Files  186 passed (186)   Tests   3169 passed  (3169)

Reverse verification — the mount-table pin can actually fail. With the implementation committed, the _migrate-stored gate was mutated back to endpoints.items and the pin re-run:

PRE  maintenance-gates=3   items-gates=1        (on-disk anchor counts, before)
POST maintenance-gates=2   items-gates=2        (after — the mutation really landed)
MUTATED hash=fa4e02a4… (was 4d20c874…)
Tests  2 failed | 22 passed (24)                ABLATION vitest exit=1
RESTORE: hash=4d20c874… head=4d20c874… — git diff HEAD empty

Direction observed, stated rather than assumed: two rows reddened, not one — metadata.endpoints.items grew a route and metadata.endpoints.maintenance lost one. That is the set-difference-in-both-directions property the pin is built on, demonstrated rather than asserted.

Cross-package type check — the declaration really was rebuilt. A probe compiled against @objectstack/spec's rebuilt dist/*.d.ts from inside packages/rest:

leg A (no `maintenance`): exit=2
  src/__dts-probe.ts(3,14): error TS2741: Property 'maintenance' is missing in type
  '{ types: true; items: true; item: true; }' but required in type
  '{ types: boolean; items: boolean; item: boolean; maintenance: boolean; schema?: undefined; }'
leg B (control, with it):  exit=0, 0 probe errors

So the green typecheck above read a fresh declaration, not a cache. The probe file was removed and the removal verified.

Gates — restated accurately, correcting the previous round. The earlier body claimed "102 families derived; all 102 run; authored to green". The 102 count and the reconciliation were real, but the conclusion drawn from them was not: the derivation does not reach packages/qa/dogfood, so a full derived-family run was structurally incapable of running the gate that was red.

$ node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack | wc -l
102
$ node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack | grep -i 'dogfood\|qa'
(no output)

The derived list is still 102 on the current change set, unchanged by the repair (it adds no new path). Re-run this round, all EXIT=0: check:nul-bytes, check:cross-package-test-inputs, check:test-source-alias, check:changeset-gate-self-tests, check:objectui-changeset, check:type-check-coverage — the families the repair's own two files touch. The remaining families were run at 484601894 on a file surface the repair does not change. CI is the authority on the full farm, and the census gate is now green locally; its CI verdict on this head is what settles it.

The derivation gap is filed as #16285, not fixed here.

⚠️ dispatch-gates also reported STALE TREE — derived from a tree at least 34 commit(s) behind origin/main, and 12 file(s) it derives from CHANGED across that range. The family list may therefore be short of families added on main since this branch forked; that half is the PM's to read against real CI, not something this branch can settle locally.

Lint — no narrowing was needed: the repo-wide authority ran whole. pnpm lint (eslint . --no-inline-config) EXIT=0 in 58s at 484601894; the repair touches two files and no lint configuration.

Collision check, read as instructed: scripts/check-single-claim-paths.mjs declares exactly one single-writer path, .objectui-sha. packages/rest/src/rest-server.ts is deliberately not on that list (the header's measurement rejects merely-hot files), so that gate can give no signal here — it passes, and its pass is not a clearance. The zero-quota substitute: git ls-remote --heads origin (1182 heads) matches no branch naming rest-server, metadata-endpoint, 15854, 15544 or 15851.

Known fleet CI defect, not this PR's: if Test Core (1/6) shows cancelled at a 30-minute timeout while the aggregate Test Core reports success, that is #16173 (amplifier #16157). ⛔ Do not re-run it, do not raise the timeout, do not touch scripts/test-shard-timings.json. On 484601894 it did not fire: Test Core (1/6) succeeded in 24m03s (07:40:21Z → 08:04:24Z), read from the check runs directly.

Generated by Claude Code